/*
 * Copyright (C) 2010 TopCoder Inc., All Rights Reserved.
 */
package com.hercules.xre.protocol.testing;

import java.util.List;


/**
 * <p>
 * This interface defines the API contract for handling events coming from a client via the
 * ProtocolTestingConnectionManager. It handles all events, including ones relating to
 * a connection being set up or stopped, either via deliberate shutdown or disconnection.
 * </p>
 *
 * <p>
 * <strong>Thread-safety:</strong> Implementations will need to be effectively thread-safe.
 * </p>
 *
 * @author TCSDESIGNER, TCSDEVELOPER
 * @version 1.0
 */
public interface EventHandler {
    /**
     * <p>
     * Handles an event to connect. Note : The parameters are guaranteed to be passed.
     * It will throw no exceptions, and implementations must handle any errors internally.
     * </p>
     *
     * @param event the event requesting a connection. Will be non-null
     *
     * @throws EventHandlerException If any error occurred while handling the event.
     * @throws IllegalArgumentException if event is invalid.
     */
    public void handleConnectionCreated(String event) throws EventHandlerException;

    /**
     * <p>
     * Handles an event for the given session. Note : The parameters are guaranteed to be
     * passed. It will throw no exceptions, and implementations must handle any errors internally.
     * </p>
     *
     * @param sessionGUID the GUID of the session for which the event is applicable.
     *        A non-null/empty string will be passed
     * @param event the event requesting a connection. Will be non-null
     *
     * @throws EventHandlerException If any error occurred while handling the event.
     *
     * @throws IllegalArgumentException if event is invalid.
     */
    public void handleConnectionEvent(String sessionGUID, String event)
        throws EventHandlerException;

    /**
     * <p>
     * Handles the case when a connection has been disconnected. It is passed the session GUID
     * and the commands that were not sent due to the disconnection. Note : The parameters are
     * guaranteed to be passed. It will throw no exceptions, and implementations must handle any
     * errors internally.
     * </p>
     *
     * @param sessionGUID the GUID of the session for which the event is applicable.
     *        A non-null/empty string will be passed
     * @param unsentCommands the list of commands that could not be sent because of
     *        the disconnection. A non-null list will be passed with no null elements
     *
     * @throws EventHandlerException If any error occurred while handling the event.
     * @throws IllegalArgumentException if any parameter is invalid.
     */
    public void handleConnectionDisconnected(String sessionGUID, List<String> unsentCommands)
        throws EventHandlerException;

    /**
     * <p>
     * Handles an event to shutdown the session. Note : The parameters are guaranteed to be
     * passed. It will throw no exceptions, and implementations must handle any errors internally.
     * </p>
     *
     * @param sessionGUID the GUID of the session for which the event is applicable.
     *        A non-null/empty string will be passed
     * @param event the event requesting a connection. Will be non-null
     *
     * @throws EventHandlerException If any error occurred while handling the event.
     * @throws IllegalArgumentException if any parameter is invalid.
     */
    public void handleConnectionShutdown(String sessionGUID, String event)
        throws EventHandlerException;
}
